package com.xuesinuo.pignoo.core;

import java.util.Collection;
import java.util.function.Function;

/**
 * PignooWriter是Pignoo提供的List
 * <p>
 * PignooWriter is a List provided by Pignoo
 * <p>
 * 特点1 - 基于SQL操作：对List的操作，会被转为SQL操作，从而实现对数据库的操作
 * <p>
 * Features 1 - Based on SQL operation: The operations on the List will be converted to SQL operations, so that the database can be operated
 * <p>
 * 特点2 - 延迟查询：在使用过滤、排序后，不会立刻查询数据库，而是将查询条件缓存下来，在调用get等终结方法时查询
 * <p>
 * Features 2 - Lazy query: After filtering and sorting, the query will not be executed immediately, but the query conditions will be cached, and the query will be executed when the get method is
 * called
 * <p>
 * 特点3 - 筛选：筛选逻辑与{@link java.util.List}一致，可以把PignooWriter当成普通List用
 * <p>
 * Features 3 - Filter: The filtering logic is consistent with {@link java.util.List}, and you can treat PignooWriter as a normal List
 * <p>
 * 特点4 - JavaBean代理：查询出的JavaBean会被代理，操作从List取出的JavaBean时，数据会保存到数据库
 * <p>
 * Features 4 - JavaBean proxy: The JavaBean queried will be proxied, and the data will be saved to the database when the JavaBean is operated from the List
 *
 * @param <E> JavaBean Type
 * @author xuesinuo
 * @since 0.1.0
 * @version 1.1.0
 */
public interface PignooWriter<E> extends PignooReader<E> {
    /**
     * 新增一条数据
     * <p>
     * Add a data
     *
     * @param e 数据
     *          <p>
     *          Data
     * @return 新增后的数据（从List反查出来的）
     *         <p>
     *         Data after adding (retrieved from the List)
     */
    E add(E e);

    /**
     * 取出并移除第一条数据
     * <p>
     * Take out and remove the first data
     * 
     * @return 第一条数据
     *         <p>
     *         First data
     * @since 1.1.0
     */
    E pollFirst();

    /**
     * 取出并移除任意一条满足条件的数据
     * <p>
     * Take out and remove any data that meets the condition
     * 
     * @return 任意一条满足条件的数据
     *         <p>
     *         Any data that meets the condition
     * @since 1.1.0
     */
    E pollAny();

    /**
     * 根据ID修改数据：混入不为NULL的属性
     * <p>
     * Modify data by Primary-Key: mix in properties that are not NULL
     *
     * @param e 含ID的数据
     *          <p>
     *          data with Primary-Key
     * @return 受影响条数
     *         <p>
     *         Number of affected entries
     */
    long mixById(E e);

    /**
     * 修改数据：混入不为NULL的属性
     * <p>
     * Modify data: mix in properties that are not NULL
     *
     * @param e 数据
     *          <p>
     *          Data
     * @return 受影响条数
     *         <p>
     *         Number of affected entries
     */
    long mixAll(E e);

    /**
     * 根据ID修改数据：完全替换
     * <p>
     * Modify data by Primary-Key: completely replace
     *
     * @param e 含ID的数据
     *          <p>
     *          data with Primary-Key
     * @return 受影响条数
     *         <p>
     *         Number of affected entries
     */
    long replaceById(E e);

    /**
     * 修改数据：完全替换
     * <p>
     * Modify data: completely replace
     *
     * @param e 数据
     *          <p>
     *          Data
     * @return 受影响条数
     *         <p>
     *         Number of affected entries
     */
    long replaceAll(E e);

    /**
     * 根据ID删除数据
     * <p>
     * Delete data by Primary-Key
     *
     * @param e 含ID的实体
     *          <p>
     *          data with Primary-Key
     * @return 受影响条数
     *         <p>
     *         Number of affected entries
     */
    long removeById(E e);

    /**
     * 删除数据
     * <p>
     * Delete data
     *
     * @return 受影响条数
     *         <p>
     *         Number of affected entries
     */
    long removeAll();

    @Override
    PignooWriter<E> sort(Function<E, ?> field, PignooSorter.SMode mode);

    @Override
    PignooWriter<E> sort(PignooSorter<E> sorter);

    @Override
    PignooWriter<E> filter(Boolean condition, Function<E, ?> field, PignooFilter.FMode mode, Object... values);

    @Override
    PignooWriter<E> filter(Boolean condition, Function<E, ?> field, String mode, Object... values);

    @Override
    PignooWriter<E> filter(Function<E, ?> field, PignooFilter.FMode mode, Object... values);

    @Override
    PignooWriter<E> filter(Function<E, ?> field, String mode, Object... values);

    @Override
    PignooWriter<E> filter(PignooFilter<E> filter);

    @Override
    PignooWriter<E> filter(Function<PignooFilter<E>, PignooFilter<E>> filterBuilder);

    @Override
    PignooWriter<E> filter(Boolean condition, Function<E, ?> field, PignooFilter.FMode mode, Collection<?> values);

    @Override
    PignooWriter<E> filter(Boolean condition, Function<E, ?> field, String mode, Collection<?> values);

    @Override
    PignooWriter<E> filter(Function<E, ?> field, PignooFilter.FMode mode, Collection<?> values);

    @Override
    PignooWriter<E> filter(Function<E, ?> field, String mode, Collection<?> values);
}
